.\" -*- nroff -*-
.\" Copyright (c) 2015      University of Houston.  All rights reserved.
.\" Copyright (c) 2015      Mellanox Technologies, Inc.
.\" $COPYRIGHT$
.de Vb
.ft CW
.nf
..
.de Ve
.ft R

.fi
..
.TH "SHMALLOC" "3" "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#"
.SH NAME

\fIshmem_malloc\fP(3),
\fIshmem_free\fP(3),
\fIshmem_align\fP(3),
\fIshmem_realloc\fP(3)
\fIshmalloc\fP(3),
\fIshfree\fP(3),
\fIshmemalign\fP(3),
\fIshrealloc\fP(3)
\- Symmetric heap memory management functions.
.SH SYNOPSIS

C or C++:
.Vb
#include <mpp/shmem.h>

void *shmem_malloc(size_t size);
void *shmalloc(size_t size);

void shmem_free(void *ptr);
void shfree(void *ptr);

void *shmem_realloc(void *ptr, size_t size);
void *shrealloc(void *ptr, size_t size);

void *shmem_align(size_t alignment, size_t size);
void *shmemalign(size_t alignment, size_t size);

extern long malloc_error;
.Ve
.SH DESCRIPTION

The \fBshmem_malloc\fP
function returns a pointer to a block of at least size bytes
suitably aligned for any use. This space is allocated from the symmetric heap (in contrast
to \fImalloc\fP(3C),
which allocates from the private heap).
.PP
The \fBshmem_align\fP
function allocates a block in the symmetric heap that has a
byte alignment specified by the alignment argument.
.PP
The \fBshmem_free\fP
function causes the block to which ptr points to, to be deallocated,
that is, made available for further allocation. If ptr is a null pointer, no action
occurs; otherwise, if the argument does not match a pointer earlier returned by a symmetric
heap function, or if the space has already been deallocated, malloc_error is set to indicate the
error, and shfree returns.
.PP
The \fBshmem_realloc\fP
function changes the size of the block to which ptr points to, to the
size (in bytes) specified by size.
.PP
The contents of the block are unchanged up to the lesser of the new and old sizes. If the new
size is larger, the value of the newly allocated portion of the block is indeterminate. If ptr is a
null pointer, the shrealloc function behaves like the shmalloc function for the specified size. If
size is 0 and ptr is not a null pointer, the block to which it points to is freed. Otherwise, if ptr
does not match a pointer earlier returned by a symmetric heap function, or if the space has
already been deallocated, the malloc_error variable is set to indicate the error, and shrealloc
returns a null pointer. If the space cannot be allocated, the block to which ptr points to is
unchanged.
.PP
The shmem_malloc, shmem_free, and shmem_realloc functions are provided so that multiple PEs in an
application can allocate symmetric, remotely accessible memory blocks. These memory
blocks can then be used with (shmem) communication routines. Each of these functions call
the \fIshmem_barrier_all\fP(3)
function before returning; this ensures that all PEs
participate in the memory allocation, and that the memory on other PEs can be used as soon
as the local PE returns.
.PP
The user is responsible for calling these functions with identical argument(s) on all PEs; if
differing size arguments are used, subsequent calls may not return the same symmetric heap
address on all PEs.
.PP
.SH NOTES

The total size of the symmetric heap is determined at job startup. One can adjust the size of
the heap using the SHMEM_SYMMETRIC_HEAP_SIZE environment variable. See the
\fIintro_shmem\fP(3)
man page for futher details.
The shmem_malloc, shmem_free, and shmem_realloc functions differ from the private heap allocation functions
in that all PEs in an application must call them (a barrier is used to ensure this).
.PP
.SH RETURN VALUES

The \fBshmem_malloc\fP
function returns a pointer to the allocated space (which should
be identical on all PEs); otherwise, it returns a null pointer (with malloc_error set).
The \fBshmem_free\fP
function returns no value.
The \fBshmem_realloc\fP
function returns a pointer to the allocated space (which
may have moved); otherwise, it returns a null pointer (with malloc_error set).
.SH SEE ALSO

\fIintro_shmem\fP(3),
\fIshmem_my_pe\fP(3I),
\fIshmem_init\fP(3)
